Inside Macintosh: QuickDraw GX Programmer's Overview / Part 2 - The QuickDraw GX Programming Cookbook

Chapter 5 - Using Macintosh Windows

Adding Scrolling to a Window

This programming recipe adds scrolling functionality to a window by editing the child view port object you created in the previous recipe. To make room for the scroll bars, you need to set the clip of your child view port, as shown in Figure 5-3.

Figure 5-3 A window with scroll bars and the corresponding view port hierarchy

The origin of the child view port originally matches the origin of the parent view port, which is the upper-left corner of the window. To scroll the contents of the window, you simply change the mapping of the child view port to offset its origin from its parent's origin, as shown in Figure 5-4.

Figure 5-4 Scrolled window contents

Overview of Recipe Steps

The steps in this recipe show you how to:

1. Create a Macintosh window and a view port hierarchy
2. Set the clip property of the child view port
3. Scroll by setting the mapping property of the child view port

Follow the instructions in each step of this recipe to draw QuickDraw GX shapes into a window with scroll bars.

Functions Used in This Recipe

QuickDraw GX functions used in this recipe:

GXNewRectangle	"Geometric Shapes" QuickDraw GX Graphics
GXSetViewPortClip	"View-Related Objects" QuickDraw GX Objects
GXGetViewPortMapping	"View-Related Objects" QuickDraw GX Objects
MoveMapping	"QuickDraw GX Mathematics" QuickDraw GX Environment and Utilities
GXDisposeShape	"Shape Objects" QuickDraw GX Objects

Standard Macintosh functions used in this recipe:

MoveControl	"Control Manager" Macintosh Toolbox Essentials
SizeControl	"Control Manager" Macintosh Toolbox Essentials
SetControlMaximum	"Control Manager" Macintosh Toolbox Essentials
SetControlValue	"Control Manager" Macintosh Toolbox Essentials
TrackControl	"Control Manager" Macintosh Toolbox Essentials
GetControlValue	"Control Manager" Macintosh Toolbox Essentials
ScrollRect	"Basic QuickDraw" Imaging With QuickDraw

This recipe gives a brief description of these functions; you can find complete reference information for these functions in the Inside Macintosh suite of books.

Recipe Step Descriptions

In this section each step is described individually.

1. Create a Macintosh window and a view port hierarchy

   To provide a Macintosh window and a view port hierarchy, you should follow the steps from the previous recipe, "Resizing and Zooming a Window," beginning on page 161.

   You can create scroll bars for the window using the GetNewControl standard Macintosh function, and you can adjust the location, size, and settings of the scroll bars using the standard Macintosh functions MoveControl, SizeControl, SetControlMaximum, and SetControlValue.

2. Set the clip property of the child view port

   In the previous recipe, you defined the MySetContentViewPortClip function to remove the area covered by the window's size box from the clip of the child view port. To provide for scroll bars, you need to change the function definition:

   void MySetContentViewPortClip(WindowPtr theWindow, 
                                 gxViewPort theChildViewPort)
   {
       gxRectangle parentBounds, contentBounds;
       gxShape contentClip;

       contentClip = MyGetWindowBoundsShape();

       GXGetRectangle(contentClip, &parentBounds);

       contentBounds.top    = parentBounds.top;
       contentBounds.left   = parentBounds.left;
       contentBounds.bottom = parentBounds.bottom 
                              - ff(kScrollBarWidth);
       contentBounds.right  = parentBounds.right 
                              - ff(kScrollBarWidth);

       contentClip = GXNewRectangle(&contentBounds);
       GXSetViewPortClip(theChildViewPort, contentClip);

       GXDisposeShape(contentClip);
   }

   This new function definition sets the clip of the child view port to be the bounding rectangle of the window minus the area covered by the scroll bars. Notice that it uses the MyGetWindowBoundsShape sample function defined in the previous recipe.

3. Scroll by setting the mapping property of the child view port

   When the user clicks in a scroll bar, you use standard Macintosh functions, like TrackControl, GetControlValue, and SetControlValue, to track and update your scroll bars and determine how much the user scrolled. You can also use the standard Macintosh function ScrollRect to scroll the contents already drawn in the window.

   Before you update the rest of the window, however, you need to shift the origin of the child view port in relation to the origin of the parent view port (which is always the upper-left corner of the window). By setting the mapping property of the child view port appropriately, you can move the origin of the view port to account for the scrolling. The next time you draw shapes into the child view port--in response to an update event, for instance--QuickDraw GX maps them using the child view port mapping, and so they appear in the correct (scrolled) locations.

   If you've used the standard Macintosh functions mentioned above to find out how far the user scrolled, and stored the horizontal scroll distance in the variable hScroll and the vertical scroll distance in the variable vScroll, you can use this code to update the mapping of the child view port:

   gxMapping viewPortMapping;

   GXGetViewPortMapping(gContentViewPort, &viewPortMapping);

   MoveMapping(&viewPortMapping, ff(hScroll), ff(vScroll));

   Once the mapping of the child view port is set, you can redraw your scroll bars, and then update the contents of your window.

Related Recipes

You should be familiar with the information in the previous two recipes in
this chapter before using the information in this recipe. The previous two recipes are:

• "Attaching a View Port to a Macintosh Window," beginning on page 161, which shows how to create a Macintosh window and attach a view port object to it.
• "Resizing and Zooming a Window," described next, shows how to handle resize and zoom boxes in your windows.

The recipes in the previous chapter, "Using the QuickDraw GX Environment," show you how to initialize QuickDraw GX and set up the QuickDraw GX debugging facilities. You should read the recipes in that chapter before using any recipes in this chapter.

The recipes in Chapter 6, "Handling Graphics," and in Chapter 7, "Handling Typography," show you how to create and manipulate images to draw into a window.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help